feat(‎lambda-events): Improve ergonomics of `SqsBatchResponse` and `KinesisEventResponse` #1063

lmammino · 2025-11-24T17:34:00Z

📬 Issue #, if available:

Related to [aws_lambda_events] No longer able to construct response types a lambda may return as a response (they are non_exhaustive) #1060

✍️ Description of changes

This PR improves the ergonomics of working with SqsBatchResponse and
KinesisEventResponse.

Since v1.0, these structs have been marked as #[non_exhaustive], which means you
can no longer construct them and provide their content in a single expression.

Note

This is also the case for the related structs SqsBatchItemFailure and
KinesisBatchItemFailure.

❌ Previous (pre-1.0, now broken) API

The following code used to be valid before 1.0, but no longer compiles:

use aws_lambda_events::event::sqs::{SqsEvent, SqsBatchResponse,
SqsBatchItemFailure};

async fn function_handler(
    event: LambdaEvent<SqsEvent>
) -> Result<SqsBatchResponse, Error> {
    let mut batch_item_failures = Vec::new();

    for record in event.payload.records {
        let message_id = record.message_id.clone().unwrap_or_default();

        // Try to process the message
        if let Err(e) = process_record(&record).await {
            println!("Failed to process message {}: {}", message_id, e);
            // Add to failures list so it will be retried
            batch_item_failures.push(SqsBatchItemFailure {
                item_identifier: message_id,
            });
        }
    }

    // Return the list of failed messages
    Ok(SqsBatchResponse {
        batch_item_failures,
    })
}

// ...

⚠️ Current (working but verbose) pattern

With #[non_exhaustive], you now need something slightly more verbose, similar to
the official example in the repo
([advanced-sqs-partial-batch-failures](https://github.com/aws/aws-lambda-rust-runti
me/blob/main/examples/advanced-sqs-partial-batch-failures/src/main.rs)):

use aws_lambda_events::event::sqs::{SqsEvent, SqsBatchResponse,
SqsBatchItemFailure};

async fn function_handler(
    event: LambdaEvent<SqsEvent>
) -> Result<SqsBatchResponse, Error> {
    let mut batch_item_failures = Vec::new();

    for record in event.payload.records {
        let message_id = record.message_id.clone().unwrap_or_default();

        // Try to process the message
        if let Err(e) = process_record(&record).await {
            println!("Failed to process message {}: {}", message_id, e);

            // Build failure using Default because SqsBatchItemFailure is
#[non_exhaustive]
            let mut failure = SqsBatchItemFailure::default();
            failure.item_identifier = message_id;

            // Add to failures list so it will be retried
            batch_item_failures.push(failure);
        }
    }

    // Return the list of failed messages
    let mut response = SqsBatchResponse::default();
    response.batch_item_failures = batch_item_failures;

    Ok(response)
}

// ...

This works, but it is more verbose and a bit less ergonomic for a very common usage
pattern.

✅ Proposed (this PR): ergonomic helper API

This PR adds two helper methods to both SqsBatchResponse and
KinesisEventResponse:

add_failure(item_identifier) - Add a single failure to the response
set_failures(item_identifiers) - Set multiple failures at once (replaces
any existing failures)

Both methods accept flexible input types via impl Into<String>, so you can pass
&str, String, or any other compatible type.

SQS Example using `add_failure`:

use aws_lambda_events::event::sqs::{SqsEvent, SqsBatchResponse};

async fn function_handler(
    event: LambdaEvent<SqsEvent>,
) -> Result<SqsBatchResponse, Error> {
    let mut response = SqsBatchResponse::default();

    for record in event.payload.records {
        let message_id = record.message_id.clone().unwrap_or_default();

        if let Err(e) = process_record(&record).await {
            println!("Failed to process message {}: {}", message_id, e);
            response.add_failure(message_id);
        }
    }

    Ok(response)
}

// ...

SQS Example using `set_failures`:

use aws_lambda_events::event::sqs::{SqsEvent, SqsBatchResponse};

async fn function_handler(
    event: LambdaEvent<SqsEvent>,
) -> Result<SqsBatchResponse, Error> {
    let mut failed_ids = Vec::new();

    for record in event.payload.records {
        let message_id = record.message_id.clone().unwrap_or_default();

        if let Err(e) = process_record(&record).await {
            println!("Failed to process message {}: {}", message_id, e);
            failed_ids.push(message_id);
        }
    }

    let mut response = SqsBatchResponse::default();
    response.set_failures(failed_ids);

    Ok(response)
}

// ...

Kinesis Example using `add_failure`:

use aws_lambda_events::event::kinesis::KinesisEvent;
use aws_lambda_events::event::streams::KinesisEventResponse;

async fn function_handler(
    event: LambdaEvent<KinesisEvent>,
) -> Result<KinesisEventResponse, Error> {
    let mut response = KinesisEventResponse::default();

    for record in event.payload.records {
        let sequence_number = record.kinesis.sequence_number.clone();

        if let Err(e) = process_record(&record).await {
            println!("Failed to process record {}: {}", sequence_number, e);
            response.add_failure(sequence_number);
        }
    }

    Ok(response)
}

// ...

This keeps the types #[non_exhaustive] while restoring a convenient and
discoverable way to build partial batch responses.

🔏 By submitting this pull request

I confirm that I've run cargo +nightly fmt.
I confirm that I've run cargo clippy --fix.
I confirm that I've made a best-effort attempt to update all relevant
documentation.
I confirm that my contribution is made under the terms of the Apache 2.0
license.

…ntResponse

jlizen

The external API seems fine to me. Though, need to get consensus with maintainers about both having codegenned builders and these sort of extra-ergonomic constructors as discussed in #1060

Left some feedback around making this more maintainable using ..Default::default() constructor syntax since we are crate-local.

We probably should also explicitly state in doc comments that all fields besides the one being set, will use the defaults for the struct (which will generally be None, an allocation-free empty string or map, etc, though that doesn't need to go in doc comments).

jlizen · 2025-12-02T19:32:31Z

lambda-events/src/event/sqs/mod.rs

+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run


minor: any reason this needs to be no_run?

jlizen · 2025-12-02T19:33:03Z

lambda-events/src/event/sqs/mod.rs

+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run


minor: any reason this needs to be no_run?

jlizen · 2025-12-02T19:38:01Z

lambda-events/src/event/sqs/mod.rs

+    /// }
+    /// ```
+    pub fn add_failure(&mut self, message_id: impl Into<String>) {
+        self.batch_item_failures.push(BatchItemFailure {


Is there a reason not to use ..Default::default() here to reduce churn in this function as the struct evolves? We shouldn't be limited by #[non_exhaustive] locally to the crate?

Ie:

self.batch_item_failures.push(BatchItemFailure { item_identifier: message_id.into(), ...Default::default() };

We also should state in the doc comment that defaults will be used for all fields besides item_identifier.

jlizen · 2025-12-02T19:38:24Z

lambda-events/src/event/sqs/mod.rs

+    {
+        self.batch_item_failures = message_ids
+            .into_iter()
+            .map(|id| BatchItemFailure {


Same feedback using ..Default::default() for future proofing, mentioning that defaults are used for other fields.

jlizen · 2025-12-02T19:38:29Z

lambda-events/src/event/streams/mod.rs

+    /// to be enabled in your Lambda function's Kinesis event source mapping configuration.
+    /// Without this setting, Lambda will retry the entire batch on any failure.
+    pub fn add_failure(&mut self, item_identifier: impl Into<String>) {
+        self.batch_item_failures.push(KinesisBatchItemFailure {


Same feedback using ..Default::default() for future proofing, mentioning that defaults are used for other fields.

jlizen · 2025-12-02T19:38:36Z

lambda-events/src/event/streams/mod.rs

+    /// **Important**: This feature requires `FunctionResponseTypes: ReportBatchItemFailures`
+    /// to be enabled in your Lambda function's Kinesis event source mapping configuration.
+    /// Without this setting, Lambda will retry the entire batch on any failure.
+    pub fn set_failures<I, S>(&mut self, item_identifiers: I)


Same feedback using ..Default::default() for future proofing, mentioning that defaults are used for other fields.

jlizen · 2025-12-02T19:51:35Z

Update - I spoke with other maintainers, and we're happy to accept this contribution with the above comments addressed! Thanks for this :)

@PartiallyUntyped will follow up in #1060 about the broader plans around codegenned builders, how they relate to these fine-tuned constructors, etc, but we don't need to let that block this PR.

jlizen · 2025-12-02T19:57:20Z

Looks like some CI failures as well due to the new doc tests. I don't mind adding lambda_runtime and tokio to dev-dependencies to get the doctests compiling. I'd prefer that to marking them no-compile since that doesn't age well.

It's also fine to rip out the usage samples if you prefer, though I do think they are pretty useful.

I think it will keep requiring that I approve the CI runs for you, which I am happy to, but you should be able to repro these failures on your fork as well to validate a fix.

lmammino added 2 commits November 24, 2025 18:21

feat: Improve ergonomics of SqsBatchResponse

cbecf2b

chore: fmt + clippy

a80c1e5

lmammino changed the title ~~feat: Improve ergonomics of SqsBatchResponse~~ feat(‎lambda-events): Improve ergonomics of SqsBatchResponse Nov 24, 2025

lmammino changed the title ~~feat(‎lambda-events): Improve ergonomics of SqsBatchResponse~~ feat(‎lambda-events): Improve ergonomics of SqsBatchResponse Nov 24, 2025

chore: better docs

ecdc5c6

lmammino mentioned this pull request Nov 24, 2025

[aws_lambda_events] No longer able to construct response types a lambda may return as a response (they are non_exhaustive) #1060

Open

lmammino added 2 commits November 25, 2025 09:53

feat: add set_failures helper and improve add_failure ergonomics

f94fb4d

feat(kinesis): add add_failure and set_failures helpers to KinesisEve…

acb971f

…ntResponse

lmammino changed the title ~~feat(‎lambda-events): Improve ergonomics of SqsBatchResponse~~ feat(‎lambda-events): Improve ergonomics of SqsBatchResponse and KinesisEventResponse Nov 25, 2025

jlizen reviewed Dec 2, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(‎lambda-events): Improve ergonomics of `SqsBatchResponse` and `KinesisEventResponse` #1063

feat(‎lambda-events): Improve ergonomics of `SqsBatchResponse` and `KinesisEventResponse` #1063

lmammino commented Nov 24, 2025 •

edited

Loading

Uh oh!

jlizen left a comment •

edited

Loading

Uh oh!

jlizen Dec 2, 2025

Uh oh!

jlizen Dec 2, 2025

Uh oh!

jlizen Dec 2, 2025 •

edited

Loading

Uh oh!

jlizen Dec 2, 2025 •

edited

Loading

Uh oh!

jlizen Dec 2, 2025 •

edited

Loading

Uh oh!

jlizen Dec 2, 2025 •

edited

Loading

Uh oh!

jlizen commented Dec 2, 2025

Uh oh!

jlizen commented Dec 2, 2025 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat(‎lambda-events): Improve ergonomics of SqsBatchResponse and KinesisEventResponse #1063

Are you sure you want to change the base?

feat(‎lambda-events): Improve ergonomics of SqsBatchResponse and KinesisEventResponse #1063

Conversation

lmammino commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

❌ Previous (pre-1.0, now broken) API

⚠️ Current (working but verbose) pattern

✅ Proposed (this PR): ergonomic helper API

SQS Example using add_failure:

SQS Example using set_failures:

Kinesis Example using add_failure:

Uh oh!

jlizen left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jlizen Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

jlizen Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

jlizen Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jlizen Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jlizen Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jlizen Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jlizen commented Dec 2, 2025

Uh oh!

jlizen commented Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat(‎lambda-events): Improve ergonomics of `SqsBatchResponse` and `KinesisEventResponse` #1063

feat(‎lambda-events): Improve ergonomics of `SqsBatchResponse` and `KinesisEventResponse` #1063

lmammino commented Nov 24, 2025 •

edited

Loading

SQS Example using `add_failure`:

SQS Example using `set_failures`:

Kinesis Example using `add_failure`:

jlizen left a comment •

edited

Loading

jlizen Dec 2, 2025 •

edited

Loading

jlizen Dec 2, 2025 •

edited

Loading

jlizen Dec 2, 2025 •

edited

Loading

jlizen Dec 2, 2025 •

edited

Loading

jlizen commented Dec 2, 2025 •

edited

Loading